home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / include / stdio.h < prev    next >
C/C++ Source or Header  |  1992-08-05  |  13KB  |  380 lines
  1. /*
  2.  * stdio.h --
  3.  *
  4.  *    This header file declares the stdio library facilities.  They
  5.  *    provide a general stream facility and routines for formatted
  6.  *    input and output.
  7.  *
  8.  * Copyright 1986, 1988 Regents of the University of California
  9.  * Permission to use, copy, modify, and distribute this
  10.  * software and its documentation for any purpose and without
  11.  * fee is hereby granted, provided that the above copyright
  12.  * notice appear in all copies.  The University of California
  13.  * makes no representations about the suitability of this
  14.  * software for any purpose.  It is provided "as is" without
  15.  * express or implied warranty.
  16.  *
  17.  * $Header: /sprite/src/lib/include/RCS/stdio.h,v 1.28 92/08/05 11:17:34 ouster Exp $ SPRITE (Berkeley)
  18.  */
  19.  
  20. #ifndef _STDIO_H
  21. #define _STDIO_H
  22.  
  23. /* 
  24.  * sprite.h is needed for typedefs that are used in some function
  25.  * prototypes.  Unfortunately, some user programs define conflicting
  26.  * typedefs.  Because practically everyone uses stdio.h, only include
  27.  * <sprite.h> if function prototypes are enabled (i.e. we're in the
  28.  * kernel or the user has explicitly asked for prototypes).
  29.  */
  30. #include <cfuncproto.h>
  31.  
  32. #ifdef _HAS_PROTOTYPES
  33. #include <sprite.h>
  34. #endif
  35.  
  36. #ifndef EOF
  37. #define EOF (-1)
  38. #endif
  39.  
  40. #ifndef NULL
  41. #define NULL 0
  42. #endif
  43.  
  44. #ifndef _CLIENTDATA
  45. typedef int *ClientData;
  46. #define _CLIENTDATA
  47. #endif
  48.  
  49. #ifndef _VA_LIST
  50. #define _VA_LIST
  51. typedef char *va_list;
  52. #endif
  53.  
  54. /*
  55.  * The main data structure used by the stdio module is a FILE.  This
  56.  * describes a byte-sequential communication channel.  The channel
  57.  * includes buffer storage and the names of three stream-dependent
  58.  * procedures:
  59.  *
  60.  * The procedure readProc is called when another byte of data is needed
  61.  * and the buffer is empty (readCount == 0).  It should read more data
  62.  * into the buffer, reset readCount and lastAccess, and set the STDIO_EOF
  63.  * flag and/or status field if any problem occurred while reading the data.
  64.  *
  65.  * The writeProc procedure is similar to readProc, except that it is
  66.  * called when the buffer has filled (writeCount just became zero);
  67.  * its job is to write out the contents of the buffer and reset
  68.  * lastAccess and writeCount.  If the flush parameter is non-zero, then
  69.  * the procedure is being called as part of fflush, and it MUST empty
  70.  * the buffer.  Otherwise, the procedure may, if it chooses, increase
  71.  * the size of the buffer and return without actually writing anything.
  72.  *
  73.  * The third procedure, closeProc, is called when the stream is closed
  74.  * (writeProc is also called on close, before closeProc).  CloseProc
  75.  * should take any client-specific closing actions, such as closing
  76.  * the file corresponding to the stream or freeing the buffer space
  77.  * for the stream.  Its return value will be the return value from
  78.  * the fclose call.  If an error occurs while closing the stream, then
  79.  * the FILE structure should not be de-allocated, since the client will
  80.  * need to get at information in it to find out what went wrong.
  81.  *
  82.  * The procedures have the following calling sequences:
  83.  *
  84.  *    void readProc(stream)
  85.  *        FILE *stream;
  86.  *    {
  87.  *    }
  88.  
  89.  *    void writeProc(stream, flush)
  90.  *        FILE *stream;
  91.  *        Boolean flush;
  92.  *    {
  93.  *    }
  94.  
  95.  *    int closeProc(stream)
  96.  *        FILE *stream;
  97.  *    {
  98.  *    }
  99.  *
  100.  * See StdIoFileReadProc, StdIoFileWriteProc, and StdIoFileCloseProc for
  101.  * examples of these procedures.
  102.  */
  103.  
  104. typedef struct _file {
  105.     unsigned char *lastAccess;    /* Place (in buffer) from which last input
  106.                  * or output byte was read or written
  107.                  * (respectively). */
  108.     int readCount;        /* # of characters that may be read from
  109.                  * buffer before calling readProc to refill
  110.                  * the buffer. */
  111.     int writeCount;        /* # of characters that may be written into
  112.                  * buffer before calling writeProc to empty
  113.                  * the buffer.  WriteProc is called immediately
  114.                  * when the buffer fills, so that this value
  115.                  * is never zero unless the stream is not
  116.                  * currently being used for writing. */
  117.     unsigned char *buffer;    /* Pointer to storage for characters.  NULL
  118.                  * means storage hasn't been allocated yet. */
  119.     int bufSize;        /* Total number of bytes of storage available
  120.                  * in buffer. 0 means storage for buffer hasn't
  121.                  * been allocated yet. */
  122.     void (*readProc)_ARGS_((struct _file *));
  123.                 /* Procedure called to refill buffer. */
  124.     void (*writeProc)_ARGS_((struct _file *, Boolean));
  125.                 /* Procedure called to empty buffer. */
  126.     int (*closeProc)_ARGS_((struct _file *));
  127.                 /* Procedure called to close stream.  NULL
  128.                  * means no procedure to call. */
  129.     ClientData clientData;    /* Additional data for the use of the
  130.                  * procedures above,  e.g. the stream ID used
  131.                  * in kernel calls. */
  132.     int status;            /* Non-zero means an error has occurred while
  133.                  * emptying or filling the buffer.  This field
  134.                  * is set by readProc and writeProc. */
  135.     int flags;            /* Miscellaneous flags.  See below for values.
  136.                  */
  137.     struct _file *nextPtr;    /* For file streams, this is used to link all
  138.                  * file streams together (NULL means end of
  139.                  * list).  For other types of streams, it can
  140.                  * be used for anything desired by the
  141.                  * stream implementor. */
  142. } FILE;
  143.  
  144. /* Flags for FILEs:
  145.  *
  146.  * STDIO_READ:        Means that this stream is used for input.
  147.  * STDIO_WRITE:        Means that this stream is used for output.
  148.  * STDIO_EOF:        Means that an end-of-file has been encountered
  149.  *            on this stream.  All future reads will fail.
  150.  * STDIO_LINEBUF:    Means that this stream is line-buffered:  flush when
  151.  *            a newline is output or stdin is read.
  152.  * STDIO_NOT_OUR_BUF:      Means that the buffer for the stream belongs to someone
  153.  *                  else and should not be freed by the stdio library.
  154.  * 
  155.  */
  156.  
  157. #define STDIO_READ        1
  158. #define STDIO_WRITE        2
  159. #define STDIO_EOF        4
  160. #define STDIO_LINEBUF        8
  161. #define STDIO_NOT_OUR_BUF    16
  162.  
  163. /*
  164.  *----------------------------------------------------------------------
  165.  *
  166.  * getc --
  167.  * getchar --
  168.  * putc --
  169.  * putchar --
  170.  *
  171.  *    These four macros are used to input the next character from
  172.  *    a FILE or output the next character to a FILE.  Normally they
  173.  *    just move a character to or from a buffer, but if the buffer is
  174.  *    full (or empty) then they call a slow procedure to empty (or fill)
  175.  *    the buffer.
  176.  *
  177.  *    These macros are somewhat gross. putc is a ternary operator
  178.  *    to allow people to say things like
  179.  *
  180.  *        if (a)
  181.  *              putc(stdout, '\n');
  182.  *        else ...
  183.  *
  184.  *    If it were a complex expression, the compiler would complain.
  185.  *
  186.  * Results:
  187.  *    None.
  188.  *
  189.  * Side effects:
  190.  *    Information is modified in stream's buffer.
  191.  *
  192.  *----------------------------------------------------------------------
  193.  */
  194.  
  195. #ifndef lint
  196. #define getc(stream)                             \
  197.     (((stream)->readCount <= 0) ?                                       \
  198.         fgetc(stream) :                        \
  199.         ((stream)->readCount -= 1,                             \
  200.          (stream)->lastAccess += 1,                        \
  201.          *((stream)->lastAccess)))
  202.  
  203. #define putc(c, stream)                                                \
  204.     ((((stream)->writeCount <= 1) || ((stream)->flags & STDIO_LINEBUF)) ? \
  205.         fputc(c, stream) :                                  \
  206.         ((stream)->writeCount -= 1,                                    \
  207.          (stream)->lastAccess += 1,                                    \
  208.          *(stream)->lastAccess = c))
  209. #else
  210. _EXTERN int getc _ARGS_((FILE stream));
  211. _EXTERN int putc _ARGS_((int c, FILE stream));
  212. #endif
  213.  
  214. #define getchar() getc(stdin)
  215.  
  216. #define putchar(c) putc(c, stdout)
  217.  
  218. /*
  219.  *----------------------------------------------------------------------
  220.  *
  221.  * ferror --
  222.  * feof --
  223.  *
  224.  *    These two macros return information about whether an error
  225.  *    or end-of-file condition has occurred on a stream.
  226.  *
  227.  * Results:
  228.  *    ferror returns 0 if no error has occurred on the stream;
  229.  *    if an error has occurred then it returns the error code.
  230.  *    feof returns 0 if no end-of-file has been encountered on
  231.  *    the stream, and TRUE (non-zero) if an end-of-file has been
  232.  *    encountered.
  233.  *
  234.  * Side effects:
  235.  *    None.
  236.  *
  237.  *----------------------------------------------------------------------
  238.  */
  239.  
  240. #define ferror(stream) ((stream)->status)
  241. #define feof(stream) ((stream)->flags & STDIO_EOF)
  242.  
  243.  
  244. /*
  245.  *----------------------------------------------------------------------
  246.  *
  247.  * Miscellaneous additional things exported by stdio:
  248.  *
  249.  *----------------------------------------------------------------------
  250.  */
  251.  
  252. /*
  253.  * Handles for standard input and output channels.
  254.  */
  255.  
  256. extern FILE stdioInFile, stdioOutFile, stdioErrFile;
  257. #define stdin    (&stdioInFile)
  258. #define stdout    (&stdioOutFile)
  259. #define stderr    (&stdioErrFile)
  260.  
  261. /*
  262.  * Default buffer size:
  263.  */
  264.  
  265. #define BUFSIZ            4096
  266.  
  267. /*
  268.  * Flags to setvbuf:
  269.  */
  270.  
  271. #define _IOFBF        1
  272. #define _IOLBF        2
  273. #define _IONBF        3
  274.  
  275. /*
  276.  * Relative position indicator for fseek:
  277.  */
  278.  
  279. #define SEEK_SET    0
  280. #define SEEK_CUR    1
  281. #define SEEK_END    2
  282.  
  283. /*
  284.  *----------------------------------------------------------------------
  285.  *
  286.  * Procedures exported by the stdio module:
  287.  * (Note that these declarations are missing the "const" modifiers
  288.  * found in the ANSI version...)
  289.  * 
  290.  *----------------------------------------------------------------------
  291.  */
  292.  
  293. _EXTERN void    clearerr _ARGS_((FILE *stream));
  294. _EXTERN int    fclose _ARGS_((FILE *stream));
  295. _EXTERN FILE *    fdopen _ARGS_((int streamID, char *access));
  296. _EXTERN int    fflush _ARGS_((FILE *stream));
  297. _EXTERN int    fgetc _ARGS_((FILE *stream));
  298. _EXTERN char *    fgets _ARGS_((char *bufferPtr, int maxChars, FILE *stream));
  299. _EXTERN int    fileno _ARGS_((FILE *stream));
  300. _EXTERN FILE *    fopen _ARGS_((_CONST char *fileName, _CONST char *access));
  301. _EXTERN int    fputc _ARGS_((int c, FILE *stream));
  302. _EXTERN int    fputs _ARGS_((char *string, FILE *stream));
  303. _EXTERN int    fread _ARGS_((char *bufferPtr, int size, int numItems,
  304.                   FILE *stream));
  305. _EXTERN FILE *    freopen _ARGS_((_CONST char *fileName,
  306.                                 _CONST char *access, FILE *stream));
  307. _EXTERN long    fseek _ARGS_((FILE *stream, long offset, int base));
  308. _EXTERN long    ftell _ARGS_((FILE *stream));
  309. _EXTERN int    fwrite _ARGS_((char *bufferPtr, int size, int numItems,
  310.                    FILE *stream));
  311. _EXTERN char *    gets _ARGS_((char *bufferPtr));
  312. _EXTERN int    getw _ARGS_((FILE *stream));
  313. _EXTERN void    perror _ARGS_((_CONST char *msg));
  314. _EXTERN FILE *    popen _ARGS_((_CONST char *cmd, char *mode));
  315. _EXTERN int    pclose _ARGS_((FILE *ptr));
  316. _EXTERN int      remove _ARGS_((_CONST char *filename));
  317. _EXTERN int      rename _ARGS_((_CONST char *oldname, _CONST char *newname));
  318.  
  319. #ifdef KERNEL
  320. /*
  321.  * Special-case declarations for kernels:
  322.  * Printf returns void because the old Sys_Printf did.
  323.  * Varargs declarations aren't easy to do across all machines, so 
  324.  * we'll punt on them for now.
  325.  */
  326. _EXTERN void    printf _ARGS_(());
  327. _EXTERN int    fprintf _ARGS_(());
  328. _EXTERN int    scanf _ARGS_(());
  329. _EXTERN char *    sprintf _ARGS_(());
  330. _EXTERN int    sscanf _ARGS_(());
  331. _EXTERN int    fscanf _ARGS_(());
  332. _EXTERN int    vfprintf _ARGS_(());
  333. _EXTERN int    vfscanf _ARGS_(());
  334. _EXTERN int    vprintf _ARGS_(());
  335. _EXTERN char *    vsprintf _ARGS_(());
  336. #else /* KERNEL */
  337. /* 
  338.  * User-mode declarations for the routines in the special-case section:
  339.  * Note that the prototype declarations are actually no-ops until 
  340.  * _ARGS_ is turned on for user code.  Also, the varargs declarations 
  341.  * are only a first cut; there no guarantee they'll actually work when 
  342.  * _ARGS_ is turned on.
  343.  */
  344. _EXTERN int    printf _ARGS_((_CONST char *format, ...));
  345. _EXTERN int    fprintf _ARGS_((FILE *stream, _CONST char *format, ...));
  346. _EXTERN int    scanf _ARGS_((_CONST char *format, ...));
  347. _EXTERN char *    sprintf _ARGS_((char *s, _CONST char *format, ...));
  348. _EXTERN int    sscanf _ARGS_((char *s, _CONST char *format, ...));
  349. _EXTERN int    fscanf _ARGS_((FILE *stream, _CONST char *format, ...));
  350. _EXTERN int    vfprintf _ARGS_((FILE *stream,
  351.                                  _CONST char *format, va_list args));
  352. _EXTERN int    vfscanf _ARGS_((FILE *stream,
  353.                                 _CONST char *format, va_list args));
  354. _EXTERN int    vprintf _ARGS_((_CONST char *format, va_list args));
  355. _EXTERN char *    vsprintf _ARGS_((char *string,
  356.                                  _CONST char *format, va_list args));
  357. #endif /* KERNEL */
  358.  
  359. _EXTERN int    puts _ARGS_((_CONST char *string));
  360. _EXTERN int    putw _ARGS_((int w, FILE *stream));
  361. _EXTERN void    rewind _ARGS_((FILE *stream));
  362. _EXTERN void    setbuf _ARGS_((FILE *stream, char *buf));
  363. _EXTERN void    setbuffer _ARGS_((FILE *stream, char *buf, int size));
  364. _EXTERN void    setlinebuf _ARGS_((FILE *stream));
  365. _EXTERN int    setvbuf _ARGS_((FILE *stream, char *buf, int mode, int size));
  366. _EXTERN FILE *    tmpfile _ARGS_((void));
  367. _EXTERN char *    tmpnam _ARGS_((char *s));
  368. _EXTERN char *    tempnam _ARGS_((char *dir, char *pfx));
  369. _EXTERN int    ungetc _ARGS_((int c, FILE *stream));
  370. _EXTERN void    _cleanup _ARGS_((void));
  371.  
  372. _EXTERN void    Stdio_Setup _ARGS_((FILE *stream, int readable, int writable,
  373.                 unsigned char *buffer, int bufferSize,
  374.                 void (*readProc)(FILE * file),
  375.                 void (*writeProc)(FILE * file, Boolean flush),
  376.                 int (*closeProc)(FILE * file),
  377.                 ClientData clientData));
  378.  
  379. #endif /* _STDIO_H */
  380.